Following are the main features and qualities associated with the _id field:
Document IdentificationThe document _id field serves as the primary key identifying the document in Ditto.
Customizable Identifier:If preferred, you can customize the _id as a string or JSON‑object. (See Custom Document Identifier)
**Retrieval by **_idYou can fetch a document by its identifier. For more information, see Fetching a Document by _id.

​
Auto-Generated Document Identifier

When inserting a document, unless manually supplied, Ditto automatically generates and assigns the new document a 128‑bit Universally Unique Identifier (UUID) to the _id field. 

let result = await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: [
    newCar: ["color": "blue"]
  ]);

// "507f191e810c19729de860ea"
print(result.mutatedDocumentIDs()[0])

​
Custom Document Identifier

If supplying your own document ID, you can encode your value in a string or, if forming a composite key, a JSON-object.
You can configure a custom document ID only at the time of document creation.Once a document is created, to ensure consistency and uniqueness throughout the platform, the unique identifier that either Ditto automatically generated and assigned or you manually assigned becomes permanent and cannot be changed at a later time.
Following are a few key principles for handling IDs in Ditto:
  • Do not include personally identifiable information (PII) in IDs
  • IDs should be immutable; that is, unchangeable once assigned and permanent
  • If an ID is formed by multiple fields, referred to as a composite key, those fields are not individually indexed

​
Supplying a Custom String Identifier

The following snippet demonstrates creating a new document assigned the string value 123. 

let result = await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: [
    newCar: [ "_id": "123", "color": "blue"]
  ]);

// "123"
print(result.mutatedDocumentIDs()[0])

​
Forming a Composite Key Identifier

The decision to opt for a composite key depends on your specific use case. Following are typical use cases for forming a composite key:
  • To implement additional logic to handle (or prevent) duplicate writes.
  • To simplify queries and enhance efficiency in the querying process.
To form a composite key, set the _id to a JSON object when inserting a new document. The following snippet demonstrates combining the vin and make fields to form a composite key: 

let arguments = [
  newCar: [ "_id": [vin: "123", make: "Toyota"], "color": "blue"]
];

let result = await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: arguments);

// "{vin: "123", make: "Toyota"}"
print(result.mutatedDocumentIDs()[0])

​
Fetching a Document by _id

Retrieve a document by its identifier (_id):
DQL
SELECT *
FROM cars
WHERE _id = '123'
If querying a composite key identifier, use dot (.) notation:
DQL
SELECT *
FROM cars
WHERE _id.model = 'Toyota'
For more information, see IDs, Paths, Strings, and Keywords and Operator Expressions in Ditto Query Language.